.TH std::unique_lock 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::unique_lock \- std::unique_lock

.SH Synopsis
   Defined in header <mutex>
   template< class Mutex >    \fI(since C++11)\fP
   class unique_lock;

   The class unique_lock is a general-purpose mutex ownership wrapper allowing deferred
   locking, time-constrained attempts at locking, recursive locking, transfer of lock
   ownership, and use with condition variables.

   The class unique_lock is movable, but not copyable -- it meets the requirements of
   MoveConstructible and MoveAssignable but not of CopyConstructible or CopyAssignable.

   The class unique_lock meets the BasicLockable requirements. If Mutex meets the
   Lockable requirements, unique_lock also meets the Lockable requirements (ex.: can be
   used in std::lock); if Mutex meets the TimedLockable requirements, unique_lock also
   meets the TimedLockable requirements.

.SH Template parameters

   Mutex - the type of the mutex to lock. The type must meet the BasicLockable
           requirements

   Nested types

   Type       Definition
   mutex_type Mutex

.SH Member functions

                  constructs a unique_lock, optionally locking (i.e., taking ownership
   constructor    of) the supplied mutex
                  \fI(public member function)\fP
   destructor     unlocks (i.e., releases ownership of) the associated mutex, if owned
                  \fI(public member function)\fP
                  unlocks (i.e., releases ownership of) the mutex, if owned, and
   operator=      acquires ownership of another
                  \fI(public member function)\fP
.SH Locking
   lock           locks (i.e., takes ownership of) the associated mutex
                  \fI(public member function)\fP
                  tries to lock (i.e., takes ownership of) the associated mutex without
   try_lock       blocking
                  \fI(public member function)\fP
                  attempts to lock (i.e., takes ownership of) the associated
   try_lock_for   TimedLockable mutex, returns if the mutex has been unavailable for
                  the specified time duration
                  \fI(public member function)\fP
                  tries to lock (i.e., takes ownership of) the associated TimedLockable
   try_lock_until mutex, returns if the mutex has been unavailable until specified time
                  point has been reached
                  \fI(public member function)\fP
   unlock         unlocks (i.e., releases ownership of) the associated mutex
                  \fI(public member function)\fP
.SH Modifiers
   swap           swaps state with another std::unique_lock
                  \fI(public member function)\fP
                  disassociates the associated mutex without unlocking (i.e., releasing
   release        ownership of) it
                  \fI(public member function)\fP
.SH Observers
   mutex          returns a pointer to the associated mutex
                  \fI(public member function)\fP
   owns_lock      tests whether the lock owns (i.e., has locked) its associated mutex
                  \fI(public member function)\fP
   operator bool  tests whether the lock owns (i.e., has locked) its associated mutex
                  \fI(public member function)\fP

.SH Non-member functions

   std::swap(std::unique_lock) specialization of std::swap for unique_lock
   \fI(C++11)\fP                     \fI(function template)\fP

.SH Example


// Run this code

 #include <iostream>
 #include <mutex>
 #include <thread>

 struct Box
 {
     explicit Box(int num) : num_things{num} {}

     int num_things;
     std::mutex m;
 };

 void transfer(Box& from, Box& to, int num)
 {
     // don't actually take the locks yet
     std::unique_lock lock1{from.m, std::defer_lock};
     std::unique_lock lock2{to.m, std::defer_lock};

     // lock both unique_locks without deadlock
     std::lock(lock1, lock2);

     from.num_things -= num;
     to.num_things += num;

     // “from.m” and “to.m” mutexes unlocked in unique_lock dtors
 }

 int main()
 {
     Box acc1{100};
     Box acc2{50};

     std::thread t1{transfer, std::ref(acc1), std::ref(acc2), 10};
     std::thread t2{transfer, std::ref(acc2), std::ref(acc1), 5};

     t1.join();
     t2.join();

     std::cout << "acc1: " << acc1.num_things << "\\n"
                  "acc2: " << acc2.num_things << '\\n';
 }

.SH Output:

 acc1: 95
 acc2: 55

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to              Behavior as published              Correct behavior
   LWG 2981 C++17      redundant deduction guide from                  removed
                       unique_lock<Mutex> was provided

.SH See also

   lock        locks specified mutexes, blocks if any are unavailable
   \fI(C++11)\fP     \fI(function template)\fP
   lock_guard  implements a strictly scope-based mutex ownership wrapper
   \fI(C++11)\fP     \fI(class template)\fP
   scoped_lock deadlock-avoiding RAII wrapper for multiple mutexes
   \fI(C++17)\fP     \fI(class template)\fP
   mutex       provides basic mutual exclusion facility
   \fI(C++11)\fP     \fI(class)\fP
